今天要來介紹 GitHub Copilot 的 Custom Instructions，也就是把團隊的技術架構、程式撰寫規則、測試方式與安全檢查，整理成一份 Markdown 指引，讓 AI 在動手寫程式之前，先讀規則、再開始施工。

先從團隊共同遵守的開發規範開始
🧭 為什麼要建立 Custom Instructions？
如果是一個人開發，可能憑自己的習慣寫就好；但是一旦變成多人協作，每個人都叫 AI 用自己的方式寫，專案很快就會變成「各路英雄好漢齊聚一堂」，看起來熱鬧，維護起來想哭。

有人要求使用 Vue Composition API，有人喜歡把所有東西塞進單一檔案，有人堅持 Clean Code，有人覺得能跑就好。這些規則如果只存在每個人的腦袋裡，最後一定會出現「我以為你知道」的經典悲劇。

📌 Custom Instructions 的任務
告訴 Copilot 這個 Repository 採用什麼技術架構。
統一程式碼風格與目錄結構。
規定建置、測試、Lint 與驗證方式。
提醒 AI 注意安全性、輸入驗證與不要硬編碼機密。
降低 AI 亂搜尋、亂試、建置失敗與反覆踩坑的機率。

GitHub Copilot Custom Instructions 的三種使用範圍

1️⃣ Repository-wide
.github/copilot-instructions.md
適用於整個 Repository，是最主要的共同規範。

2️⃣ Path-specific
.github/instructions/*.instructions.md
針對特定路徑、檔案類型或工作範圍補充規則。

3️⃣ Agent instructions
AGENTS.md、CLAUDE.md、GEMINI.md
因應不同 AI Agent 的使用情境。

✍️ 使用自然語言與 Markdown 撰寫 instruction
Instruction 怎麼寫？重點是通則，不是每一個例外，用自然語言搭配 Markdown 來寫，不需要什麼神秘格式，也不用把它寫成一篇「宇宙級規格書」。真正重要的是：這份檔案要描述通則，而不是把所有特殊案例、一次性任務與個人偏好全部塞進去。

✅ 適合放進全域 instruction 的內容
技術堆疊，例如 Node.js、Vue、TypeScript。
後端分層方式，例如 Controller → Service → Repository。
元件大小、共用邏輯與目錄配置原則。
Clean Code、SOLID、輸入驗證與安全性要求。
完成前要執行的 build、lint、test 或驗證步驟。

⚠️ 不適合全部塞進全域 instruction 的內容
某一個頁面才會遇到的特殊處理。
只適用於單一檔案或單一資料夾的規則。
今天這個任務才需要的一次性需求。
特殊規則就放到 path-specific instruction，任務需求則直接寫在 Prompt 裡。通則歸通則，特例歸特例，這樣 AI 才不會讀到最後開始懷疑人生。

🚧 最大魔王關：instruction 最怕規則彼此衝突
這一段是筆者覺得最重要、也最容易被忽略的地方。當 instruction 越寫越多，最怕的不是內容少，而是規則互相打架。

例如前面說「所有元件都要拆小」，後面又說「這個頁面請集中在同一個檔案」；一開始說要寫測試，後面又要求為了速度不要寫測試。AI 看到這種 A 變 B 的規則，很可能就會卡住，或是自作主張選一個結果。到時候你問它為什麼這樣寫，它還可以很有自信地回答你，這才是最可怕的地方啊 😨

🛠️ 筆者實作一：建立一份 Web Development Guideline
接下來進入實作。在 VS Code 裡使用 Copilot Chat，請它協助建立 Web Development Guideline。畫面中可以看到，Copilot 先檢查目前的工作區與相關自訂規則，再建立 instruction 檔案。

這種做法的好處是不用從空白頁開始想，筆者可以先讓 AI 依照既有結構產生草稿，再把不適合的內容刪掉、把模糊的描述改清楚。

在 .github/instructions 底下建立客製化 instruction
如果是特定領域，也可以請 AI 產生 security、API、Always Wrap Obtaining 之類的專用規則，然後放在適當的客製化目錄。

📄 筆者實作二：設定專案的技術架構與開發準則
這次的範例專案是一個 Vue + TypeScript 的 BMI 網站，因此在 .github/copilot-instructions.md 裡寫入以下方向：

Web Development Guideline

Tech stack: Node.js and run at Port:3131, Vue 3, TypeScript.

Use Vue 3 Composition API and keep components small.

Backend should follow:
Controller → Service → Repository

Separate UI, business logic, validation, and data access.

Apply SOLID and Clean Code principles.
Avoid duplicate code, any, magic numbers, deep nesting,
and unnecessary abstractions.

Validate external input and never hard-code secrets.

Before completion, run lint, tests, and build.

Implementation is complete only when validation succeeds
with no new errors.

這裡面有技術堆疊、Vue 的開發方式、元件拆分、後端分層、Clean Code、安全性與完成前驗證。看起來都是基本功，但問題是基本功最容易被忘記，尤其當 AI 開始高速產生程式碼時，更需要一份檔案在旁邊拉住它。

BMI 網站成功在 localhost:3131 執行
網站開啟後，可以輸入身高與體重，按一下按鈕就計算 BMI，結果也會顯示健康體重等分類。從成果來看，Copilot 確實有跟著定義的規則走，並且完成網站啟動。

更多實作細節，請參考完整版影片囉

🎬 本日結論：instruction 是從 Vibe Coding 走向架構思維的重要一步
當你開始認真撰寫這種 instruction，代表你已經逐漸從 Vibe Coding 走向 Architecture Design，也就是不只是叫 AI「幫我做一個網站」，而是開始定義它應該用什麼方式做、如何驗證、什麼情況才算完成。

這個轉變非常重要。AI 是很強的菜鳥工程師，速度快、產量高、偶爾自信滿滿地做錯事；我們真正要做的，不是期待它突然變成資深架構師，而是把規則、邊界與驗證方式講清楚。

規範寫得好，AI 少亂搞；架構定得牢，團隊沒煩惱啊~